Inside Macintosh: Imaging with QuickDraw
Previous | Chapter Top | Chapter Contents | Next |
To create an offscreen graphics world, use the NewGWorld function. The NewGWorld function uses the NewScreenBuffer function to create and allocate memory for an offscreen pixel image; your application generally won't need to use NewScreenBuffer , but it is described here for completeness. The NewGWorld function similarly uses the NewTempScreenBuffer function to create and allocate temporary memory for an offscreen pixel image.
To change the pixel depth, boundary rectangle, or color table for an existing offscreen graphics world, use the UpdateGWorld function.
When you no longer need the pixel image associated with this offscreen graphics world, use the DisposeGWorld procedure to dispose of all the memory allocated for the offscreen graphics world. The DisposeGWorld procedure uses the DisposeScreenBuffer procedure when disposing of an offscreen graphics world; generally, your application won't need to use DisposeScreenBuffer .
Before drawing into an offscreen graphics world, be sure to use the SetGWorld procedure (described on SetGWorld ) to make that offscreen world the current graphics port. In addition, before drawing into--or copying from--an offscreen pixel map, be sure to use the LockPixels function, which is described on LockPixels .
Use the NewGWorld function to create an offscreen graphics world.
FUNCTION NewGWorld (VAR offscreenGWorld: GWorldPtr;
pixelDepth: Integer; boundsRect: Rect;
cTable: CTabHandle; aGDevice: GDHandle;
flags: GWorldFlags): QDErr;
TYPE GWorldFlags =
SET OF ( {flags for only NewGWorld are listed here}
pixPurge, {make base address for offscreen pixel }
{ image purgeable}
noNewDevice, {do not create an offscreen GDevice }
{ record}
useTempMem, {create base address for offscreen pixel }
{ image in temporary memory}
keepLocal, {keep offscreen pixel image in main }
{ memory where it cannot be cached to }
{ a graphics accelerator card}
);
The NewGWorld function creates an offscreen graphics world with the pixel depth you specify in the pixelDepth parameter, the boundary rectangle you specify in the boundsRect parameter, the color table you specify in the cTable parameter, and the options you specify in the flags parameter. The NewGWorld function returns a pointer to the new offscreen graphics world in the offscreenGWorld parameter. You use this pointer when referring to this new offscreen world in other routines described in this chapter.
Typically, you pass 0 in the pixelDepth parameter, a window's port rectangle in the boundsRect parameter, NIL in the cTable and aGDevice parameters, and--in the flags parameter--an empty set ([ ]) for Pascal code or 0 for C code. This provides your application with the default behavior of NewGWorld , and it supports computers running basic QuickDraw. This also allows QuickDraw to optimize the CopyBits , CopyMask , and CopyDeepMask procedures when your application copies the image in an offscreen graphics world into an onscreen graphics port.
The NewGWorld function allocates memory for an offscreen graphics port and its pixel map. On computers that support only basic QuickDraw, NewGWorld creates a 1-bit pixel map that your application can manipulate using other relevant routines described in this chapter. Your application can copy this 1-bit pixel map into basic graphics ports.
Unless you specify 0 in the pixelDepth parameter--or pass the noNewDevice flag in the flags parameter and supply a GDevice record in the aGDevice parameter-- NewGWorld also allocates a new offscreen GDevice record.
When creating an image, your application can use the NewGWorld function to create an offscreen graphics world that is optimized for an image's characteristics--for example, its best pixel depth. After creating the image, your application can then use the CopyBits , CopyMask , or CopyDeepMask procedure to copy that image to an onscreen graphics port. Color QuickDraw automatically renders the image at the best available pixel depth for the screen. Creating an image in an offscreen graphics port and then copying it to the screen in this way prevents the visual choppiness that would otherwise occur if your application were to build a complex image directly onscreen.
The NewGWorld function initializes the offscreen graphics port by calling the OpenCPort function. The NewGWorld function sets the offscreen graphics port's visible region to a rectangular region coincident with its boundary rectangle. The NewGWorld function generates an inverse table with the Color Manager procedure MakeITable , unless one of the GDevice records for the screens has the same color table as the GDevice record for the offscreen world, in which case NewGWorld uses the inverse table from that GDevice record.
The address of the offscreen pixel image is not directly accessible from the PixMap record for the offscreen graphics world. However, you can use the GetPixBaseAddr function (described on GetPixBaseAddr ) to get a pointer to the beginning of the offscreen pixel image.
For purposes of estimating memory use, you can compute the size of the offscreen pixel image by using this formula:
rowBytes * (boundsRect.bottom - boundsRect.top)
In the flags parameter, you can specify several options that are defined by the GWorldFlags data type. If you don't wish to use any of these options, pass an empty set ([ ]) in the flags parameter for Pascal code or pass 0 here for C code.
As its function result, NewGWorld returns one of three result codes.
If you supply a handle to a ColorTable record in the cTable parameter, NewGWorld makes a copy of the record and stores its handle in the offscreen PixMap record. It is your application's responsibility to make sure that the ColorTable record you specify in the cTable parameter is valid for the offscreen graphics port's pixel depth.
If when using NewGWorld you specify a pixel depth, color table, or GDevice record that differs from those used by the window into which you copy your offscreen image, the CopyBits , CopyMask , and CopyDeepMask procedures require extra time to complete.
To use a custom color table in an offscreen graphics world, you need to create the associated offscreen GDevice record, because Color QuickDraw needs its inverse table.
The NewGWorld function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
Listing 6-1 and Listing 6-2 illustrate how to use NewGWorld to create offscreen graphics worlds.
If your application needs to change the pixel depth, boundary rectangle, or color table for an offscreen graphics world, use the UpdateGWorld function, described on UpdateGWorld .
The NewGWorld function uses the NewScreenBuffer function to create an offscreen PixMap record and allocate memory for the base address of its pixel image; applications generally don't need to use NewScreenBuffer .
FUNCTION NewScreenBuffer (globalRect: Rect;
purgeable: Boolean; VAR gdh: GDHandle;
VAR offscreenPixMap: PixMapHandle):
QDErr;
The NewScreenBuffer function creates a new offscreen PixMap record, using the pixel depth and color table of the device whose GDevice record is returned in the gdh parameter. The NewScreenBuffer function returns a handle to the new offscreen pixel map in the offscreenPixMap parameter.
As its function result, NewScreenBuffer returns one of three result codes.
The NewScreenBuffer function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
The NewGWorld function uses the NewTempScreenBuffer function to create an offscreen PixMap record and allocate temporary memory for the base address of its pixel image; applications generally don't need to use NewTempScreenBuffer .
FUNCTION NewTempScreenBuffer (globalRect: Rect;
purgeable: Boolean;
VAR gdh: GDHandle;
VAR offscreenPixMap: PixMapHandle):
QDErr;
The NewTempScreenBuffer function performs the same functions as NewScreenBuffer except that it creates the base address for the offscreen pixel image in temporary memory. When an application passes it the useTempMem flag, the NewGWorld function uses NewTempScreenBuffer instead of NewScreenBuffer .
To change the pixel depth, boundary rectangle, or color table for an existing offscreen graphics world, use the UpdateGWorld function. You should call UpdateGWorld after every update event and whenever your windows move or change size.
FUNCTION UpdateGWorld (VAR offscreenGWorld: GWorldPtr;
pixelDepth: Integer; boundsRect: Rect;
cTable: CTabHandle; aGDevice: GDHandle;
flags: GWorldFlags): GWorldFlags;
TYPE GWorldFlags =
SET OF ( {flags for UpdateGWorld are listed here}
keepLocal, {keep data structures in main memory}
clipPix, {update and clip pixel image to new }
{ boundary rectangle}
stretchPix, {update and stretch or shrink pixel }
{ image to the new boundary rectangle}
ditherPix, {include with clipPix or stretchPix }
{ flag to dither the pixel image}
);
The UpdateGWorld function changes an offscreen graphics world to the specified pixel depth, rectangle, color table, and options that you supply in the pixelDepth , boundsRect , cTable , and flags parameters, respectively. In the offscreenGWorld parameter, pass the pointer returned to your application by the NewGWorld function when you created the offscreen graphics world.
If the LockPixels function (described on LockPixels ) reports that the Memory Manager has purged the base address for the offscreen pixel image, you can use UpdateGWorld to reallocate its memory. Your application should then reconstruct the pixel image or draw directly in a window instead of preparing the image in an offscreen graphics world.
In the flags parameter, you can specify the keepLocal flag, which keeps the offscreen pixel image in Macintosh main memory or returns the image to main memory if it had been previously cached. If you use UpdateGWorld without passing it the keepLocal flag, you allow the offscreen pixel image to be cached on a graphics accelerator card if one is present.
As its function result, UpdateGWorld returns the gwFlagErr flag if UpdateGWorld was unsuccessful; in this case, the offscreen graphics world is left unchanged. You can use the QDError function, described in the chapter "Color QuickDraw," to help you determine why UpdateGWorld failed.
If UpdateGWorld is successful, it returns a combination of the following flags, which are defined by the GWorldFlags data type:
The UpdateGWorld function uses the following algorithm when updating the offscreen pixel image:
Use the DisposeGWorld procedure to dispose of all the memory allocated for an offscreen graphics world.
PROCEDURE DisposeGWorld (offscreenGWorld: GWorldPtr);
The DisposeGWorld procedure disposes of all the memory allocated for the offscreen graphics world pointed to in the offscreenGWorld parameter, including its pixel map, color table, pixel image, and GDevice record (if one was created). In the offscreenGWorld parameter, pass the pointer returned to your application by the NewGWorld function when you created the offscreen graphics world.
Call DisposeGWorld only when your application no longer needs the pixel image associated with this offscreen graphics world. If this offscreen graphics world was the current device, the current device is reset to the device stored in the global variable MainDevice .
The DisposeGWorld procedure uses the DisposeScreenBuffer procedure when disposing of an offscreen graphics world; generally, applications do not need to use DisposeScreenBuffer .
PROCEDURE DisposeScreenBuffer (offscreenPixMap: PixMapHandle);